14.8.2.1 :var

The :var header argument is used to pass arguments to code blocks. The specifics of how arguments are included in a code block vary by language; these are addressed in the language-specific documentation. However, the syntax used to specify arguments is the same across all languages. In every case, variables require a default value when they are declared.

The values passed to arguments can either be literal values, references, or Emacs Lisp code (see Emacs Lisp evaluation of variables). References include anything in the Org mode file that takes a #+NAME: or #+RESULTS: line: tables, lists, #+BEGIN_EXAMPLE blocks, other code blocks and the results of other code blocks.

Note: When a reference is made to another code block, the referenced block will be evaluated unless it has current cached results (see cache).

Argument values can be indexed in a manner similar to arrays (see Indexable variable values).

The following syntax is used to pass arguments to code blocks using the :var header argument.

:var name=assign

The argument, assign, can either be a literal value, such as a string ‘"string"’ or a number ‘9’, or a reference to a table, a list, a literal example, another code block (with or without arguments), or the results of evaluating another code block.

Here are examples of passing values by reference:

table

an Org mode table named with either a #+NAME: line

#+NAME: example-table
| 1 |
| 2 |
| 3 |
| 4 |

#+NAME: table-length
#+BEGIN_SRC emacs-lisp :var table=example-table
(length table)
#+END_SRC

#+RESULTS: table-length
: 4

list

a simple list named with a #+NAME: line (note that nesting is not carried through to the source code block)

#+NAME: example-list
  - simple
    - not
    - nested
  - list

#+BEGIN_SRC emacs-lisp :var x=example-list
  (print x)
#+END_SRC

#+RESULTS:
| simple | list |

code block without arguments

a code block name (from the example above), as assigned by #+NAME:, optionally followed by parentheses

#+BEGIN_SRC emacs-lisp :var length=table-length()
(* 2 length)
#+END_SRC

#+RESULTS:
: 8

code block with arguments

a code block name, as assigned by #+NAME:, followed by parentheses and optional arguments passed within the parentheses following the code block name using standard function call syntax

#+NAME: double
#+BEGIN_SRC emacs-lisp :var input=8
(* 2 input)
#+END_SRC

#+RESULTS: double
: 16

#+NAME: squared
#+BEGIN_SRC emacs-lisp :var input=double(input=1)
(* input input)
#+END_SRC

#+RESULTS: squared
: 4

literal example

a literal example block named with a #+NAME: line

#+NAME: literal-example
#+BEGIN_EXAMPLE
A literal example
on two lines
#+END_EXAMPLE

#+NAME: read-literal-example
#+BEGIN_SRC emacs-lisp :var x=literal-example
  (concatenate 'string x " for you.")
#+END_SRC

#+RESULTS: read-literal-example
: A literal example
: on two lines for you.

Indexable variable values

It is possible to reference portions of variable values by “indexing” into the variables. Indexes are 0 based with negative values counting back from the end. If an index is separated by ,s then each subsequent section will index into the next deepest nesting or dimension of the value. Note that this indexing occurs before other table related header arguments like :hlines, :colnames and :rownames are applied. The following example assigns the last cell of the first row the table example-table to the variable data:

#+NAME: example-table
| 1 | a |
| 2 | b |
| 3 | c |
| 4 | d |

#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
  data
#+END_SRC

#+RESULTS:
: a

Ranges of variable values can be referenced using two integers separated by a :, in which case the entire inclusive range is referenced. For example the following assigns the middle three rows of example-table to data.

#+NAME: example-table
| 1 | a |
| 2 | b |
| 3 | c |
| 4 | d |
| 5 | 3 |

#+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
  data
#+END_SRC

#+RESULTS:
| 2 | b |
| 3 | c |
| 4 | d |

Additionally, an empty index, or the single character *, are both interpreted to mean the entire range and as such are equivalent to 0:-1, as shown in the following example in which the entire first column is referenced.

#+NAME: example-table
| 1 | a |
| 2 | b |
| 3 | c |
| 4 | d |

#+BEGIN_SRC emacs-lisp :var data=example-table[,0]
  data
#+END_SRC

#+RESULTS:
| 1 | 2 | 3 | 4 |

It is possible to index into the results of code blocks as well as tables. Any number of dimensions can be indexed. Dimensions are separated from one another by commas, as shown in the following example.

#+NAME: 3D
#+BEGIN_SRC emacs-lisp
  '(((1  2  3)  (4  5  6)  (7  8  9))
    ((10 11 12) (13 14 15) (16 17 18))
    ((19 20 21) (22 23 24) (25 26 27)))
#+END_SRC

#+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
  data
#+END_SRC

#+RESULTS:
| 11 | 14 | 17 |

Emacs Lisp evaluation of variables

Emacs lisp code can be used to initialize variable values. When a variable value starts with (, [, ' or ` it will be evaluated as Emacs Lisp and the result of the evaluation will be assigned as the variable value. The following example demonstrates use of this evaluation to reliably pass the file-name of the Org mode buffer to a code block—note that evaluation of header arguments is guaranteed to take place in the original Org mode file, while there is no such guarantee for evaluation of the code block body.

#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
  wc -w $filename
#+END_SRC

Note that values read from tables and lists will not be evaluated as Emacs Lisp, as shown in the following example.

#+NAME: table
| (a b c) |

#+HEADERS: :var data=table[0,0]
#+BEGIN_SRC perl
  $data
#+END_SRC

#+RESULTS:
: (a b c)